home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / libelf / elf.z / elf
Encoding:
Text File  |  2002-10-03  |  15.0 KB  |  256 lines
  1. ELF(3E)                                               Last changed: 9-22-98
  2.  
  3.  
  4. NNAAMMEE
  5.      eellff - Object file access library
  6.  
  7. SSYYNNOOPPSSIISS
  8.      cccc [_f_l_a_g ...] _f_i_l_e ...  --lleellff [_l_i_b_r_a_r_y ...]
  9.  
  10.      ##iinncclluuddee <<lliibbeellff..hh>>
  11.  
  12. IIMMPPLLEEMMEENNTTAATTIIOONN
  13.      IRIX systems
  14.  
  15. DDEESSCCRRIIPPTTIIOONN
  16.      Functions in the ELF access library let a program manipulate ELF
  17.      (Executable and Linking Format) object files, archive files, and
  18.      archive members.  The header file provides type and function
  19.      declarations for all library services.
  20.  
  21.      Programs communicate with many of the higher-level routines using an
  22.      ELF descriptor.  That is, when the program starts working with a file,
  23.      eellff__bbeeggiinn creates an ELF descriptor through which the program
  24.      manipulates the structures and information in the file.  These ELF
  25.      descriptors can be used both to read and to write files.  After the
  26.      program establishes an ELF descriptor for a file, it may then obtain
  27.      section descriptors to manipulate the sections of the file (see the
  28.      eellff__ggeettssccnn(3E) man page).  Sections hold the bulk of an object file's
  29.      real information, such as text, data, the symbol table, and so on.  A
  30.      section descriptor belongs to a particular ELF descriptor, just as a
  31.      section "belongs" to a file.  Finally, data descriptors are available
  32.      through section descriptors, allowing the program to manipulate the
  33.      information associated with a section.  A data descriptor "belongs" to
  34.      a section descriptor.
  35.  
  36.      Descriptors provide private handles to a file and its pieces.  In
  37.      other words, a data descriptor is associated with one section
  38.      descriptor, which is associated with one ELF descriptor, which is
  39.      associated with one file.  Although descriptors are private, they give
  40.      access to data that may be shared.  Consider programs that combine
  41.      input files, using incoming data to create or update another file.
  42.      Such a program might get data descriptors for an input and an output
  43.      section.  It then could update the output descriptor to reuse the
  44.      input descriptor's data.  That is, the descriptors are distinct, but
  45.      they could share the associated data bytes.  This sharing avoids the
  46.      space overhead for duplicate buffers and the performance overhead for
  47.      copying data unnecessarily.
  48.  
  49.    FFIILLEE CCLLAASSSSEESS
  50.      ELF provides a framework in which to define a family of object files,
  51.      supporting multiple processors and architectures.  An important
  52.      distinction among object files is the class, or capacity, of the file.
  53.      The 32-bit class supports architectures in which a 32-bit object can
  54.      represent addresses, file sizes, etc., as in the following:
  55.  
  56.      Name          Purpose
  57.  
  58.      Elf32_Addr    Unsigned address
  59.  
  60.      Elf32_Half    Unsigned medium integer
  61.  
  62.      Elf32_Off     Unsigned file offset
  63.  
  64.      Elf32_Sword   Signed large integer
  65.  
  66.      Elf32_Word    Unsigned large integer
  67.  
  68.      unsigned char Unsigned small integer
  69.  
  70.      Other classes will be defined as necessary, to support larger (or
  71.      smaller) machines.  Some library services deal only with data objects
  72.      for a specific class, while others are class-independent.  To make
  73.      this distinction clear, library function names reflect their status,
  74.      as described below.
  75.  
  76.    DDAATTAA RREEPPRREESSEENNTTAATTIIOONNSS
  77.      Conceptually, two parallel sets of objects support cross compilation
  78.      environments.  One set corresponds to file contents, while the other
  79.      set corresponds to the native memory image of the program manipulating
  80.      the file.  Type definitions supplied by the header files work on the
  81.      native machine, which may have different data encodings (size, byte
  82.      order, etc.) than the target machine.  Although native memory objects
  83.      should be at least as big as the file objects (to avoid information
  84.      loss), they may be bigger if that is more natural for the host
  85.      machine.
  86.  
  87.      Translation facilities exist to convert between file and memory
  88.      representations.  Some library routines convert data automatically,
  89.      while others leave conversion as the program's responsibility.  Either
  90.      way, programs that create object files must write file-typed objects
  91.      to those files; programs that read object files must take a similar
  92.      view.  See the eellff__xxllaattee(3E) and eellff__ffssiizzee(3E) man pages for more
  93.      information.
  94.  
  95.      Programs may translate data explicitly, taking full control over the
  96.      object file layout and semantics.  If the program prefers not to have
  97.      and exercise complete control, the library provides a higher-level
  98.      interface that hides many object file details.  eellff__bbeeggiinn and related
  99.      functions let a program deal with the native memory types, converting
  100.      between memory objects and their file equivalents automatically when
  101.      reading or writing an object file.
  102.  
  103.    EELLFF VVEERRSSIIOONNSS
  104.      Object file versions allow ELF to adapt to new requirements.  Three-
  105.      independent-versions can be important to a program.  First, an
  106.      application program knows about a particular version by virtue of
  107.      being compiled with certain header files.  Second, the access library
  108.      similarly is compiled with header files that control what versions it
  109.      understands.  Third, an ELF object file holds a value identifying its
  110.      version, determined by the ELF version known by the file's creator.
  111.      Ideally, all three versions would be the same, but they may differ.
  112.  
  113.         If a program's version is newer than the access library, the
  114.         program might use information unknown to the library.  Translation
  115.         routines might not work properly, leading to undefined behavior.
  116.         This condition merits installing a new library.
  117.  
  118.         The library's version might be newer than the program's and the
  119.         file's.  The library understands old versions, thus avoiding
  120.         compatibility problems in this case.
  121.  
  122.         Finally, a file's version might be newer than either the program or
  123.         the library understands.  The program might or might not be able to
  124.         process the file properly, depending on whether the file has extra
  125.         information and whether that information can be safely ignored.
  126.         Again, the safe alternative is to install a new library that
  127.         understands the file's version.
  128.  
  129.      To accommodate these differences, a program must use eellff__vveerrssiioonn to
  130.      pass its version to the library, thus establishing the "working
  131.      version" for the process.  Using this, the library accepts data from
  132.      and presents data to the program in the proper representations.  When
  133.      the library reads object files, it uses each file's version to
  134.      interpret the data.  When writing files or converting memory types to
  135.      the file equivalents, the library uses the program's working version
  136.      for the file data.
  137.  
  138.    SSYYSSTTEEMM SSEERRVVIICCEESS
  139.      As previously mentioned, eellff__bbeeggiinn and related routines provide a
  140.      higher-level interface to ELF files, performing input and output on
  141.      behalf of the application program.  These routines assume a program
  142.      can hold entire files in memory, without explicitly using temporary
  143.      files.  When reading a file, the library routines bring the data into
  144.      memory and perform subsequent operations on the memory copy.  Programs
  145.      that wish to read or write large object files with this model must
  146.      execute on a machine with a large process virtual address space.  If
  147.      the underlying operating system limits the number of open files, a
  148.      program can use eellff__ccnnttll to retrieve all necessary data from the file,
  149.      allowing the program to close the file descriptor and reuse it.
  150.  
  151.      Although the eellff__bbeeggiinn interfaces are convenient and efficient for
  152.      many programs, they might be inappropriate for some.  In those cases,
  153.      an application may invoke the eellff__xxllaattee data translation routines
  154.      directly.  These routines perform no input or output, leaving that as
  155.      the application's responsibility.  By assuming a larger share of the
  156.      job, an application controls its input and output model.
  157.  
  158.    LLIIBBRRAARRYY NNAAMMEESS
  159.      Names associated with the library take several forms:
  160.  
  161.      eellff__ _n_a_m_e         These class-independent names perform some service,
  162.                        _n_a_m_e, for the program.
  163.  
  164.      eellff3322___n_a_m_e        Service names with an embedded class, 3322 here,
  165.                        indicate they work only for the designated class of
  166.                        files.
  167.  
  168.      EEllff___T_y_p_e          Data types can be class-independent as well,
  169.                        distinguished by _T_y_p_e.
  170.  
  171.      EEllff3322___T_y_p_e        Class-dependent data types have an embedded class
  172.                        name, 3322 here.
  173.  
  174.      EELLFF__CC___C_M_D         Several functions take commands that control their
  175.                        actions.  These values are members of the EEllff__CCmmdd
  176.                        enumeration; they range from zero through
  177.                        EELLFF__CC__NNUUMM--11.
  178.  
  179.      EELLFF__FF___F_L_A_G        Several functions take flags that control library
  180.                        status and/or actions.  Flags are bits that may be
  181.                        combined.
  182.  
  183.      EELLFF3322__FFSSZZ___T_Y_P_E    These constants give the file sizes in bytes of the
  184.                        basic ELF types for the 32-bit class of files.  See
  185.                        eellff__ffssiizzee for more information.
  186.  
  187.      EELLFF__KK___K_I_N_D        The function eellff__kkiinndd identifies the _K_I_N_D of file
  188.                        associated with an ELF descriptor.  These values are
  189.                        members of the EEllff__KKiinndd enumeration; they range from
  190.                        zero through EELLFF__KK__NNUUMM--11.
  191.  
  192.      EELLFF__TT___T_Y_P_E        When a service function, such as eellff__xxllaattee, deals
  193.                        with multiple types, names of this form specify the
  194.                        desired _T_Y_P_E.  Thus, for example, EELLFF__TT__EEHHDDRR is
  195.                        directly related to EEllff3322__EEhhddrr.  These values are
  196.                        members of the EEllff__TTyyppee enumeration; they range from
  197.                        zero through EELLFF__TT__NNUUMM--11.
  198.  
  199. NNOOTTEESS
  200.      The standard SVR4 eellff man page mentions processor-dependent header
  201.      files with names of the form <<ssyyss//eellff___N_A_M_E..hh>> where _N_A_M_E is a
  202.      processor name in a table, such as MM3322.  There are no such header
  203.      files in _I_R_I_X.
  204.  
  205.      A 32-bit application can construct 64-bit binaries using functions
  206.      defined on the above-mentioned man pages.  However the man pages and
  207.      certain books published on SVR4 specifically document fields in the
  208.      EEllff__DDaattaa structure as lloonngg.  This restricts the generated object files
  209.      (even 64-bit object files) to have 32-bit values at most when
  210.      constructed by a 32-bit application.  The resulting object file is
  211.      always 64-bit clean (the documented 32-bit fields are only too small
  212.      during construction of the object file, not too small in the object
  213.      file itself).  This matters, for example, in the Fortran compiler
  214.      where the bbssss section might need to be greater than 32-bits.  See
  215.      //uussrr//iinncclluuddee//lliibbeellff..hh for the definition(s) of EEllff__DDaattaa.
  216.  
  217.      To overcome this difficulty, the generating application should be
  218.      compiled with the preprocessor flag __LLIIBBEELLFF__XXTTNNDD__6644 defined to all
  219.      compilation units and should link to --lleellff__xxttnndd and --llddwwaarrff__xxttnndd
  220.      instead of --lleellff and --llddwwaarrff.  If  this is done, the definition of the
  221.      fields in the EEllff__DDaattaa changes to 64 bits.  This change permeates the
  222.      definition of an EEllff ** (even though the definition of EEllff** is opaque
  223.      to the application), requiring the application build to be completely
  224.      consistent and define __LLIIBBEELLFF__XXTTNNDD__6644 everywhere in the application
  225.      build and to link with --lleellff__xxttnndd and --llddwwaarrff__xxttnndd instead of --lleellff
  226.      and --llddwwaarrff.
  227.  
  228.      It is just possible that by compiling with __LLIIBBEELLFF__XXTTNNDD__6644 visible in
  229.      some compilation units but not others an application could manage to
  230.      pass an EEllff** or other libelf structure created without __LLIIBBEELLFF__XXTTNNDD__6644
  231.      into a libelf function call compiled with __LLIIBBEELLFF__XXTTNNDD__6644.  Or vice-
  232.      versa.  The result will surely be chaos.
  233.  
  234.      __LLIIBBEELLFF__XXTTNNDD__6644 is irrelevant to any 64-bit application and the
  235.      --lleellff__xxttnndd and --llddwwaarrff__xxttnndd are not needed, since 64-bit applications
  236.      can build true 64-bit object files without defining __LLIIBBEELLFF__XXTTNNDD__6644.
  237.  
  238.      Applications which only read 64-bit object files need not use
  239.      __LLIIBBEELLFF__XXTTNNDD__6644 since the section headers, program headers, and data
  240.      of the file have 64-bit fields without __LLIIBBEELLFF__XXTTNNDD__6644 being defined.
  241.  
  242. SSEEEE AALLSSOO
  243.      eellff__bbeeggiinn(3E), eellff__ccnnttll(3E), eellff__eenndd(3E), eellff__eerrrroorr(3E), eellff__ffiillll(3E),
  244.      eellff__ffllaagg(3E), eellff__ffssiizzee(3E), eellff__ggeettaarrhhddrr(3E), eellff__ggeettaarrssyymm(3E),
  245.      eellff__ggeettbbaassee(3E), eellff__ggeettddaattaa(3E), eellff__ggeetteehhddrr(3E), eellff__ggeettiiddeenntt(3E),
  246.      eellff__ggeettpphhddrr(3E), eellff__ggeettssccnn(3E), eellff__ggeettsshhddrr(3E), eellff__hhaasshh(3E),
  247.      eellff__kkiinndd(3E), eellff__nneexxtt(3E), eellff__rraanndd(3E), eellff__rraawwffiillee(3E),
  248.      eellff__ssttrrppttrr(3E), eellff__uuppddaattee(3E), eellff__vveerrssiioonn(3E), eellff__xxllaattee(3E),
  249.      aa..oouutt(4) aarr(4)
  250.      The chapter "Object Files" in _U_N_I_X _S_Y_S_T_E_M _V _R_E_L_E_A_S_E _4 _P_r_o_g_r_a_m_m_e_r'_s
  251.      _G_u_i_d_e: _A_N_S_I _C _a_n_d _P_r_o_g_r_a_m_m_i_n_g _S_u_p_p_o_r_t _T_o_o_l_s, published by Prentice
  252.      Hall, ISBN 0-13-933706-7
  253.  
  254.      This man page is available only online.
  255.  
  256.